.\"
.\" POSTGRES95 Data Base Management System
.\" 
.\" Copyright (c) 1994-5 Regents of the University of California
.\" 
.\" POSTGRES Data Base Management System
.\" Copyright (c) 1988,1994 Regents of the University of California
.\" 
.\" Permission to use, copy, modify, and distribute this software and its
.\" documentation for any purpose, without fee, and without a written agreement
.\" is hereby granted, provided that the above copyright notice and this
.\" paragraph and the following two paragraphs appear in all copies.
.\"
.\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
.\" DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
.\" LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
.\" DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
.\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
.\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
.\" 
.\"
.\"	$Id: libpq++.3,v 1.1.1.1 1996/07/09 06:22:19 scrappy Exp $
.\"
.\" ------------------------------------------------------------------
.\" .(l, .)l
.\"	fake "-me"-style lists
.de (l 
.nf
.ie '\\$1'M' .in +0n
.el .in +5n
..
.de )l
.fi
.in
..
.\" .(C, .)C
.\"	constant-width font blocks
.de (C
.ft C
.(b
.(l \\$1
.sp
..
.de )C
.sp
.)l
.)b
.ft R
..
.\" ------------------------------------------------------------------
.de SE
.nr si 0
.nr so 0
.nr $0 0
.nr $i \\n(si*\\n($0
.in \\n($i+\\n(po
..
.\" ------------------------------------------------------------------
.de SP
.he '\fB\\$1 (\\$2)'\\$3'\\$1 (\\$2)\fR'
..
.\" ------------------------------------------------------------------
.de SS
.PP
.B \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
.PP
..
.\" ------------------------------------------------------------------
.SB
.ds II \s-1INGRES\s0
.ds PG \s-1POSTGRES95\s0
.ds UU \s-1UNIX\s0
.ds PQ \s-1POSTQUEL\s0
.ds LI \s-1LIBPQ++\s0
.ds PV 4.2
.SB
.TH INTRODUCTION LIBPQ++ 07/24/95
.XA 0 "Libpq++"
.BH "LIBPQ++"
.SH DESCRIPTION
\*(LI is the C++ API to \*(PG.  \*(LI is a set of classes which allow
client programs to connect to the \*(PG backend server. These connections
come in two forms: a Database Class and a Large Object class.
.PP
The Database Class is intended for manipulating a database. You can
send all sorts of SQL queries to the \*(PG backend server and retrieve
the responses of the server.
.PP
The Large Object Class is intended for manipulating a large object
in a database. Although a Large Object instance can send normal
queries to the \*(PG backend server it is only intended for simple
queries that do not return any data. A large object should be seen
as a file stream. In future it should behave much like the C++ file
streams
.IR cin ,
.IR cout
and
.IR cerr .
This version of the documentation is based on the C library.  Three
short programs are listed at the end of this section as examples of
\*(LI programming (though not necessarily of good programming).
.PP
There are several examples of \*(LI applications in the following
directory:
.(C
\&.../src/libpq++/examples
.)C
.XA 1 "Control and Initialization"
.SH "CONTROL AND INITIALIZATION"
.XA 2 "Environment Variables"
.SS "Environment Variables"
The following environment variables can be used to set up default
values for an environment and to avoid hard-coding database names into
an application program:
.TP 15n
.BR PGDATABASE
sets the default \*(PG database name.
.TP 15n
.BR PGHOST
sets the default server name.
.TP 15n
.BR PGOPTIONS
sets additional runtime options for the \*(PG backend.
.TP 15n
.BR PGPORT
sets the default communication port with the \*(PG backend.
.TP 15n
.BR PGTTY
sets the file or tty on which debugging messages from the backend server
are displayed.
.TP 15n
.BR PGREALM
sets the
.IR Kerberos
realm to use with \*(PG, if it is different from the local realm.  If 
.SM PGREALM
is set, \*(PG applications will attempt authentication with servers
for this realm and use separate ticket files to avoid conflicts with
local ticket files.  This environment variable is only used if 
.IR Kerberos
authentication is enabled.
.TP 15n
.BR PGAUTH
sets the type of authentication which should be used. Currently
only
.IR unauth ,
.IR krb4 ,
and
.IR krb5 .
are supported. Depending on whether you compiled in support for those.
.XA 1 "Database Connection Functions"
.SH "DATABASE ENVIRONMENT CLASS: PGenv"
The database environment class provides C++ objects for manipulating the
above environment variables.
.TP 15n
.BR PGenv
Create an environment for the running program.
.(C
PGenv()
PGenv(char* auth, char* host, char* port, char* option, char* tty)
.)C
The first form of this object's constructor sets up the defaults for
the program from the environment variables listed above.
The second allows the programmer to hardcode the values into the program.
The values of the second form relate directly to the environment variables
above.
.SH "DATABASE CLASS: PGdatabase"
The database class is a provides C++ objects that have a connection
to a backend server. To create such an object one first need
the apropriate environment for the backend to access.
The following constructors deal with making a connection to a backend
server from a C++ program.
.TP 15n
.BR PGdatabase
Make a new connection to a backend database server.
.(C
PGdatabase(PGenv *env, char *dbName); 
.)C
After a PGdatabase has been created it should be checked to make sure
the connection to the database succeded before sending
queries to the object. This can easily be done by
retrieving the current status of the PGdatabase object with the
.IR status
command.
.BR PGdatabase::status
Returns the status of the PGdatabase object.

.(C
ConnStatus PGdatabase::status()
.)C

the following values are allowed

.(C
CONNECTION_OK
CONNECTION_BAD
.)C

.XA 1 "Query Execution Functions"
.SH "QUERY EXECUTION FUNCTIONS"
.TP 15n
.BR PGdatabase::exec
Submits a query to \*(PG and returns result status. In case of an error 
.IR PGdatabase::errormessage
can be used to get more information on the error.
.(C
void
ExecStatusType PGdatabase::exec(char *query);
.)C
The following status results can be expected.
.(C
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK,  /* the query was a command */
PGRES_TUPLES_OK,  /* the query successfully returned tuples */
PGRES_COPY_OUT, 
PGRES_COPY_IN,
PGRES_BAD_RESPONSE, /* an unexpected response was received */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
.)C
.IP
If the result status is PGRES_TUPLES_OK, then the following routines can
be used to retrieve the tuples returned by the query.
.IP
.BR PGdatabase::ntuples
returns the number of tuples (instances) in the query result.
.(C
int PGdatabase::ntuples();
.)C
.BR PGdatabase::nfields
returns the number of fields (attributes) in the query result.
.(C
int PGdatabase::nfields();
.)C
.BR PGdatabase::fieldname
returns the field (attribute) name associated with the given field index.
Field indices start at 0.
.(C
char* PGdatabase::fieldname(int field_index);
.)C
.BR PGdatabase::fieldnum
returns the field (attribute) index associated with the given field name.
.(C
int PGdatabase::fieldnum(char* field_name);
.)C
.BR PGdatabase::fieldtype
returns the field type of associated with the given field index or name.
The integer returned is an internal coding of the type. Field indices start
at 0.
.(C
Oid PGdatabase::fieldtype(int field_index);
Oid PGdatabase::fieldtype(char* field_name);
.)C
.BR PGdatabase::fieldsize
returns the size in bytes of the field associated with the given field
index or name. If the size returned is -1, the field is a variable length
field. Field indices start at 0. 
.(C
int2 PGdatabase::fieldsize(int field_index);
int2 PGdatabase::fieldsize(char* field_name);
.)C
.BR PGdatabase::getvalue
returns the field (attribute) value.  For most queries, the values
returned by 
.IR PGdatabase::getvalue
is a null-terminated ASCII string representation
of the attribute value.  If the query was a result of a 
.BR BINARY
cursor, then the values returned by
.IR PGdatabase::getvalue
is the binary representation of the type in the internal format of the
backend server.  It is the programmer's responsibility to cast and
convert the data to the correct C++ type.  The value return by 
.IR PGdatabase::getvalue
points to storage that is part of the PGdatabase structure.  One must
explicitly copy the value into other storage if it is to be used past
the next query.
.(C
char* PGdatabase::getvalue(int tup_num, int field_index);
char* PGdatabase::getvalue(int tup_num, char* field_name);
.)C
.BR PGdatabase::getlength
returns the length of a field (attribute) in bytes.  If the field
is a
.IR "struct varlena" ,
the length returned here does 
.BR not
include the size field of the varlena, i.e., it is 4 bytes less.
.(C
int PGdatabase::getlength(int tup_num, int field_index);
int PGdatabase::getlength(int tup_num, char* field_name);
.)C
.BR PGdatabase::printtuples
prints out all the tuples and, optionally, the attribute names to the
specified output stream.
.(C
void PGdatabase::printtuples(
       FILE* fout,      /* output stream */
       int printAttName,/* print attribute names or not*/
       int terseOutput, /* delimiter bars or not?*/
       int width        /* width of column, variable width if 0*/
       );
.)C
.XA 1 "Asynchronous Notification"
.SH "ASYNCHRONOUS NOTIFICATION"
\*(PG supports asynchronous notification via the 
.IR LISTEN
and
.IR NOTIFY
commands.  A backend registers its interest in a particular relation
with the LISTEN command.  All backends that are listening on a
particular relation will be notified asynchronously when a NOTIFY of
that relation name is executed by another backend.   No additional
information is passed from the notifier to the listener.  Thus,
typically, any actual data that needs to be communicated is transferred
through the relation.
.PP
\*(LI applications are notified whenever a connected backend has
received an asynchronous notification.  However, the communication from
the backend to the frontend is not asynchronous.  The \*(LI application
must poll the backend to see if there is any pending notification
information.  After the execution of a query, a frontend may call 
.IR PGdatabase::notifies
to see if any notification data is currently available from the backend. 
.TP 15n
.BR PGdatabase::notifies
returns the notification from a list of unhandled notifications from the
backend. Returns NULL if there is no pending notifications from the
backend.   
.IR PGdatabase::notifies
behaves like the popping of a stack.  Once a notification is returned
from
.IR PGdatabase::notifies,
it is considered handled and will be removed from the list of
notifications.
.(C
PGnotify* PGdatabase::notifies()
.)C
.PP
The second sample program gives an example of the use of asynchronous
notification.
.XA 1 "Functions Associated with the COPY Command"
.SH "FUNCTIONS ASSOCIATED WITH THE COPY COMMAND"
The
.IR copy
command in \*(PG has options to read from or write to the network
connection used by \*(LI.  Therefore, functions are necessary to
access this network connection directly so applications may take full
advantage of this capability.
.TP 15n
.BR PGdatabase::getline
Reads a newline-terminated line of characters (transmitted by the
backend server) into a buffer 
.IR string 
of size
.IR length .
Like
.IR fgets (3),
this routine copies up to 
.IR length "-1"
characters into 
.IR string .
It is like 
.IR gets (3),
however, in that it converts the terminating newline into a null
character.
.IP
.IR PGdatabase::getline
returns EOF at EOF, 0 if the entire line has been read, and 1 if the
buffer is full but the terminating newline has not yet been read.
.IP
Notice that the application must check to see if a new line consists
of the single character \*(lq.\*(rq, which indicates that the backend
server has finished sending the results of the 
.IR copy
command.  Therefore, if the application ever expects to receive lines
that are more than
.IR length "-1"
characters long, the application must be sure to check the return
value of 
.IR PGdatabase::getline
very carefully.
.IP
.(C
int PGdatabase::getline(char* string, int length)
.)C
.TP 15n
.BR PGdatabase::putline
Sends a null-terminated 
.IR string
to the backend server.
.IP
The application must explicitly send the single character \*(lq.\*(rq
to indicate to the backend that it has finished sending its data.
.(C
void PGdatabase::putline(char* string)
.)C
.TP 15n
.BR PGdatabase::endcopy
Syncs with the backend.  This function waits until the backend has
finished processing the copy.  It should either be issued when the
last string has been sent to the backend using
.IR PGdatabase::putline
or when the last string has been received from the backend using
.IR PGdatabase::getline .
It must be issued or the backend may get \*(lqout of sync\*(rq with
the frontend.  Upon return from this function, the backend is ready to
receive the next query.
.IP
The return value is 0 on successful completion, nonzero otherwise.
.(C
int PGdatabase::endcopy()
.)C
As an example:
.(C
PGdatabase data;
data.exec("create table foo (a int4, b char16, d float8)");
data.exec("copy foo from stdin");
data.putline("3\etHello World\et4.5\en");
data.putline("4\etGoodbye World\et7.11\en");
\&...
data.putline(".\en");
data.endcopy();
.)C
.SH BUGS
The query buffer is 8192 bytes long, and queries over that length will
be silently truncated.
.bp
The PGlobj class is largely untested.  Use with caution.
